Scenario #9620: An Api Key Subject Name Must Match the Api Key Name Grammar

API_KEY subjects authenticate technical clients via the Hostsharing-Api-Key HTTP header instead of a Keycloak OIDC JWT, e.g. automation programs, completely bypassing Keycloak. Only a global-admin may create API_KEY subjects. The clear-text API-key is returned only once, in the response of creating the API_KEY subject; just its hash gets stored. Like GROUP subjects, API_KEY subjects cannot have an account. Global API_KEY subjects do not belong to a realm, thus their name must neither contain a - (the realm-prefix delimiter) nor a / (the GROUP subject marker).

Properties

Given

name	value
subjectUuid	a91c0002-0000-0000-0000-000000000002
subjectName	master-api-key

Create the API_KEY Subject

The response contains the generated clear-text API-key (property apiKey) exactly once; it cannot be retrieved again.

HTTP POST "/api/rbac/subjects" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  <<EOF
{
  "uuid" : "a91c0002-0000-0000-0000-000000000002",
  "name" : "master-api-key",
  "type" : "API_KEY"
}
EOF
=> status: 400 BAD_REQUEST 
{
  "timestamp" : "2026-08-10 04:42:38",
  "path" : "",
  "statusCode" : 400,
  "statusPhrase" : "Bad Request",
  "message" : "ERROR: [400] [API_KEY subject name 'master-api-key' does not match required pattern]"
}

---

generated on 2026-08-10 04:42:38 for branch HEAD